</> 技術筆記Tech Notes

在 Raspberry Pi 5 (Ubuntu 25.04) 上部署 PostgreSQL 17 及其 PostGIS 與 pgvector 擴充套件之技術指南

· 系統與硬體/樹莓派

1. 概覽

本文件旨在提供於 Raspberry Pi 5 硬體平台上，部署 PostgreSQL 17 資料庫系統的標準作業程序。該平台運行的作業系統為 Ubuntu Server 25.04。指南內容涵蓋 PostgreSQL 核心系統的安裝、遠端存取之組態設定，以及 PostGIS 地理空間處理與 pgvector 向量相似度搜尋兩項關鍵擴充套件的整合部署與功能驗證。

2. 系統需求

在執行本指南所述程序前，請確保符合以下條件：

  • 硬體平台： Raspberry Pi 5

  • 作業系統： Ubuntu Server 25.04 (或相容的 Debian-based 系統)

  • 權限要求： 具備 sudo 指令執行權限的有效使用者帳戶

  • 網路連線： 可存取網際網路的有效網路連線，以便下載所需套件

3. 安裝程序

3.1. 系統更新

為確保系統環境的穩定性與安全性，首先執行系統套件列表更新與已安裝套件的升級。

sudo apt update
sudo apt upgrade -y

3.2. 設定 PostgreSQL APT 儲存庫

為獲取最新的 PostgreSQL 17 版本，需設定使用其官方 APT 儲存庫。

  1. 安裝必要工具並匯入儲存庫 GPG 金鑰： 此金鑰用於驗證下載套件的完整性與來源可靠性。

    sudo apt install wget ca-certificates -y
wget -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/postgresql.gpg

  2. 新增儲存庫來源檔案： 於 /etc/apt/sources.list.d/ 目錄下建立 pgdg.list 檔案，以定義儲存庫位址。

    echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list > /dev/null

3.3. 安裝 PostgreSQL 17 套件

更新套件列表以讀取新增的儲存庫，隨後安裝 PostgreSQL 17 主程式與客戶端工具。

sudo apt update
sudo apt install postgresql-17 -y

3.4. 驗證服務狀態

確認 PostgreSQL 服務已成功安裝並自動啟動。

systemctl status [email protected]

預期輸出應包含 active (running) 字樣，表示服務已正常運作。

● [email protected] - PostgreSQL Cluster 17-main Loaded: loaded (/usr/lib/systemd/system/[email protected]; enabled-runtime; preset: enabled) Active: active (running) since Thu 2025-08-07 20:22:42 CST; 1min 24s ago Invocation: 5c447d2fab3844e09190b9f6ba4f8f77 Process: 3832 ExecStart=/usr/bin/pg_ctlcluster –skip-systemctl-redirect 17-main start (code=exited, status=0/SUCCESS) Main PID: 3837 (postgres) Tasks: 6 (limit: 19002) CPU: 244ms CGroup: /system.slice/system-postgresql.slice/[email protected] ├─3837 /usr/lib/postgresql/17/bin/postgres -D /var/lib/postgresql/17/main -c config_file=/etc/postgresql/17/main/postgresql.conf ├─3838 “postgres: 17/main: checkpointer “ ├─3839 “postgres: 17/main: background writer “ ├─3841 “postgres: 17/main: walwriter “ ├─3842 “postgres: 17/main: autovacuum launcher “ └─3843 “postgres: 17/main: logical replication launcher “

Aug 07 20:22:40 nc systemd[1]: Starting [email protected] - PostgreSQL Cluster 17-main… Aug 07 20:22:42 nc systemd[1]: Started [email protected] - PostgreSQL Cluster 17-main.

4. 遠端存取組態設定

預設組態下，PostgreSQL 僅監聽本機回環位址。以下步驟將啟用遠端網路存取。

4.1. 修改 postgresql.conf

編輯主設定檔，將服務綁定至所有網路介面。

sudo nano /etc/postgresql/17/main/postgresql.conf

尋找 listen_addresses 參數，取消其註解並將值修改為 '*'：

listen_addresses = '*'

4.2. 修改 pg_hba.conf

編輯主機基礎認證 (HBA) 檔案，新增一條規則以允許來自特定網段的客戶端連線。

sudo nano /etc/postgresql/17/main/pg_hba.conf

於檔案末尾追加以下規則，範例中允許 192.168.1.0/24 網段的所有使用者使用 md5 加密密碼進行認證。請依據實際網路環境調整位址範圍。

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             192.168.1.0/24          md5

安全提示： 應避免使用 0.0.0.0/0，因其會對所有來源 IP 開放，帶來安全風險。請採用最小權限原則。

4.3 如何為 postgres 使用者設定密碼

如果您確實需要為 postgres 超級使用者設定一個密碼（例如，為了從遠端圖形化工具登入），您可以按照以下步驟操作：

  1. 首先，使用無密碼的 peer 認證方式登入：

    sudo -u postgres psql

  2. 進入 psql 介面後，使用 \password 指令來設定密碼。它會安全地提示您輸入兩次新密碼：

    SQL

    \password postgres

    系統會提示：

    Enter new password:
Enter it again:

完成後，postgres 使用者就有了一個密碼，可以用於遠端連線時的 md5 驗證。

⚠️ 重要安全建議： 即使您為 postgres 設定了密碼，最佳實踐仍然是：不要在您的應用程式中使用 postgres 超級使用者帳戶。請永遠使用權限受限的專用使用者來連接您的應用程式，這能大幅提高系統的安全性。

4.4. 套用組態變更

重新啟動 PostgreSQL 服務以載入新的組態設定。

sudo systemctl restart postgresql.service

5. 擴充套件部署

5.1. 安裝擴充套件相依性套件

透過 apt 安裝 PostGIS 與 pgvector 的相關套件。

sudo apt install postgresql-17-postgis-3 postgresql-17-pgvector -y

5.2. 建立專用資料庫與使用者

遵循安全實踐，為應用程式建立非超級管理員權限的專用資料庫與使用者。

sudo -u postgres psql -c "CREATE USER my_project_user WITH PASSWORD 'a_secure_password';"
sudo -u postgres psql -c "CREATE DATABASE my_project_db OWNER my_project_user;"

請將 a_secure_password 替換為高強度密碼。

5.3. 於資料庫內啟用擴充套件

連線至目標資料庫並執行 CREATE EXTENSION 指令以啟用擴充功能。

sudo -u postgres psql -d my_project_db

在 psql 提示字元後執行：

CREATE EXTENSION postgis;
CREATE EXTENSION vector;

5.4. 驗證擴充套件狀態

使用 \dx 元命令查詢已安裝的擴充套件列表，確認 postgis 和 vector 已成功載入。

\dx

輸出結果：

                                List of installed extensions
  Name   | Version |   Schema   |                        Description                         
---------+---------+------------+------------------------------------------------------------
 plpgsql | 1.0     | pg_catalog | PL/pgSQL procedural language
 postgis | 3.5.2   | public     | PostGIS geometry and geography spatial types and functions
 vector  | 0.8.0   | public     | vector data type and ivfflat and hnsw access methods

6. 功能驗證

此步驟旨在確認擴充套件已正常運作並可執行其核心功能。

6.1. PostGIS 功能驗證

執行一項基本的空間資料插入與查詢操作。

-- 建立空間資料表
CREATE TABLE locations (id serial primary key, name text, geom geometry(Point, 4326));
-- 插入點位資料
INSERT INTO locations (name, geom) VALUES ('Yilan County Government', ST_SetSRID(ST_MakePoint(121.7539, 24.7541), 4326));
-- 查詢並以 WKT 格式回傳幾何物件
SELECT id, name, ST_AsText(geom) FROM locations;

6.2. pgvector 功能驗證

執行一項基本的向量資料插入與相似度搜尋操作。

-- 建立向量資料表
CREATE TABLE items (id serial primary key, embedding vector(3));
-- 插入向量資料
INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]');
-- 執行 L2 距離（歐幾里得距離）相似度搜尋
SELECT * FROM items ORDER BY embedding <-> '[1,1,1]' LIMIT 1;

7. 結論

完成本指南所有步驟後，您的 Raspberry Pi 5 系統上已成功部署 PostgreSQL 17，並已完成遠端存取設定。此外，資料庫已整合 PostGIS 與 pgvector 擴充套件，具備處理地理空間資訊與高維向量資料的能力，可作為現代化應用之後端數據儲存。